---
description: Collaborate on changes across multiple components.
labels: ['core aspect', 'cli', 'version control']
---

See more details about these two features here: [Lanes](https://github.com/teambit/bit/issues/1986). [Snaps](https://github.com/teambit/bit/issues/1985).

The following describes the final implementation, which differs from the specification above.

## Synopsis

```
- create a snap: `bit snap` (synopsis similar to the `bit tag`)
- create a new lane: `bit lane create <name>`
- list lanes: `bit lane list`
- switch between lanes: `bit switch <name>`
- merge lanes: `bit lane merge`
- show lane details: `bit lane show <name>`
- diff between lanes: `bit lane diff <values>`
- track local lane to a remote lane: `bit switch --as`
- remove a lane: `bit lane remove <name>`.
- fetch lane objects (without the components): `bit fetch --lanes`
- import a lane: `bit lane import`
- export current lane: `bit export`
- (internal) cat lane object: `bit cat-lane <name>`
```

## Important points

### Lane ID

The Lane id consists of the lane name and the scope. If this is a new lane, the scope is the defaultScope.
The `LaneId` _always_ has these two props.

### Performance consideration

Currently, if it imports with no-deps, it doesn't ask for parents, if it imports with deps it imports with all parents. It is originated from src/api/scope/lib/fetch.ts: `const collectParents = !noDependencies;`. We need to make a decision here.

### Hash

- Snap's hash is generated by a UUID and then converted into sha1. `sha1(v4())`.
- Lane's hash is generated by a UUID and then converted into sha1. `sha1(v4())`.
- Tag's hash stays the same. Generated by the `Version.id()`.
- Lane's hash doesn't get changed even if the lane has been renamed or its scope changed.

### Lane Data

Lane data, for the most cases is a map of component-id:snap-head, in other words, it saves per component the head snap. There are 3 different places where we store such data for different purposes.

- `lane-object` "Lane" is saved in the scope `.bit/objects` (.bit can be .git/bit locally), it has a unique hash and contains a map of components and their heads. This object exists on both local and remote scopes. Its main purpose is to sync lane-data between scopes. See `Lane` class (in scope/model) for the implementation details.
- `remote-lane` (component and their heads) is saved in `.bit/refs/remote/remote-name/lane-name`. These refs files are saved in both, local and remote scopes. Its main purpose is to keep track where the remote-heads are per lane. See `RemoteLanes` class for the implementation details.

More places that stores lanes related data:

- the currently checked out lane is saved in the scope.json file. (e.g. `{ lanes: { current: "lane-a", tracking: "remote/lane-a" } }`).
- When switching to a remote lane, the .bitmap is updated as well with the remote-name, so then, when cloning the project, it's possible to fetch the remote lane data.

Summary of when/what lanes data is saved per command:

- `bit lane create`: creates a new lane-object and creates a new lane record in scope.json and .bitmap.
- `bit snap`: adds an entry to the lane-object.
- `bit export`: pushes the lane-object to the remote. On the remote, the lane-object is created or updated/merged.
- `bit switch --remote`: 1) creates/updates lane-object in the scope. 2) creates/updates remote-lane. the remote-lane is updated also for main.
- `bit fetch` or `bit import --objects`: creates/updates remote-lane. the remote-lane is updated also for main. It doesn't update/merge the lane object.

### Merge during import

- When the remote is ahead, it's easy, just update the head to the remote-head.
- When the local and remote have diverged, it's more complex. We need to create a snap-merge that has two parents, one point to the local head and one point to the remote head.
- On `bit import --objects` (or `bit fetch`) we don't merge. The remote head is saved in the .bit/refs/remote dir. Then, `bit status` shows that these components are merge-pending.
- On `bit import <id>` we do the merge.
- in case the merge wasn't done and the user is trying to export, the remote blocks is as it finds out that its head doesn't exist on the incoming component.
- in case the snap-merge failed due to a conflict, it saves the conflict and heads data into `.bit/unmerged.json` file.

### Merge components

- to merge an entire lane, use `bit lane merge`.
- to get updates from a remote lane, run `bit import`, and then `bit checkout head`. alternatively, run `bit merge <component-id>` in one command.
- to merge an individual component from a lane to main, run `bit lane merge <lane> --pattern <component-id>` when on main.

### Useful APIs

- bit-map `getAllIdsAvailableOnLane()` filters the currently checked out lane.

### Remove component from a lane

Locally, to remove a component from a lane, use `bit remove` command. It will remove the component from the local lane-object.
This change won't affect the remote scope, even after exporting the lane.
This is becuase on the remote, the merge-lane process doesn't remove anything, only adds/changes components to the lane object.
Remember that by default when importing a lane, only the components on the workspace are part of the lane, so the same lane-object, locally can have less components than the remote and obviously in this case we don't want to remove them from the remote on export.

To mark a component as removed on the lane, use `bit remove --delete`, which will modify the component, mark it as removed, then, on the next snap+export, the remote will be updated.
Once a component is marked as removed, it won't be merged during `bit lane merge`, and won't be imported during `bit lane import`.

### Debug issues during merge

The merge operation performs 3-way merge to minimize the number of conflicts.
It searches the common parent of the current-snap and the other-snap. This parent-snap or base-snap is common to these two lanes.
For most case, it works as follows:
If the base and current has the same data but the other has different data, it means, the other made a change.
In which case, no need for conflicts, just bring the data from the other to the local.
On the other hand, if the base the other has the same data but the current has different data, then, the current made a change. No need to do anything.
Only when the current and the other, both are different, and both are different than the base, there is a conflict.

In case of merging lanes, and it's unclear why/how some changes were introduced or marked conflicted, go to the log to find out what is the base-snap and the other-snap.
The log message starts with "merging snaps details", and it lists per component-id the base-snap, current-snap and other-snap.
From here, you can investigate the data of each one of the snaps by running `bit cat-object -p <snap>`.
To make this process easier, there are some tools that can help. keep reading.

#### source code merges/conflicts

To find out when a change was introduced to a file or when a file was added/removed, run `bit log-file <file-path>`.
It might be helpful to create a new temporary workspace, import the other lane and run the same there.
This way, you get the full picture from both lanes when a change was introduced, and you can see whether it happened before and after the split from the base-snap.
Obviously, `bit log <comp-id> --one-line` is helpful here to see the distance from each lane from the base-snap.

#### dependencies merges/conflicts

Similar to file-changes, you can run `bit deps blame` to understhand when a dependency was introduced/deleted/changed from a component.
Here again, it'll be helpful to import to a new workspace the other lane and run the same there.
Also, becuase the dependencies merge is pretty complex, during the merge lots of valuable info is printed to the log.
However, to avoid the extra noise it is not logged as "debug" but as "trace". Before you run the merge, you can add `--log=trace` to see these messages on the screen.
